package com.kexio.email.service;

import java.util.List;
import java.util.Map;

import com.kexio.common.dto.Result;
import com.kexio.email.entity.EmailAttachment;
import com.kexio.email.entity.EmailRecord;

/**
 * 邮件服务接口
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface EmailService {
    
    /**
     * 发送简单文本邮件
     * 
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param content 邮件内容
     * @return 发送结果
     */
    Result<EmailRecord> sendTextEmail(String to, String subject, String content);
    
    /**
     * 发送HTML邮件
     * 
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param htmlContent HTML内容
     * @return 发送结果
     */
    Result<EmailRecord> sendHtmlEmail(String to, String subject, String htmlContent);
    
    /**
     * 发送带附件的邮件
     * 
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param content 邮件内容
     * @param attachments 附件列表
     * @return 发送结果
     */
    Result<EmailRecord> sendEmailWithAttachments(String to, String subject, String content, 
                                                List<EmailAttachment> attachments);
    
    /**
     * 发送模板邮件
     * 
     * @param to 收件人邮箱
     * @param templateCode 模板编码
     * @param templateParams 模板参数
     * @return 发送结果
     */
    Result<EmailRecord> sendTemplateEmail(String to, String templateCode, Map<String, Object> templateParams);
    
    /**
     * 发送模板邮件 (带附件)
     * 
     * @param to 收件人邮箱
     * @param templateCode 模板编码
     * @param templateParams 模板参数
     * @param attachments 附件列表
     * @return 发送结果
     */
    Result<EmailRecord> sendTemplateEmail(String to, String templateCode, Map<String, Object> templateParams,
                                         List<EmailAttachment> attachments);
    
    /**
     * 批量发送邮件
     * 
     * @param toList 收件人列表
     * @param subject 邮件主题
     * @param content 邮件内容
     * @param isHtml 是否HTML格式
     * @return 发送结果
     */
    Result<String> batchSendEmail(List<String> toList, String subject, String content, boolean isHtml);
    
    /**
     * 批量发送模板邮件
     * 
     * @param toList 收件人列表
     * @param templateCode 模板编码
     * @param templateParams 模板参数
     * @return 发送结果
     */
    Result<String> batchSendTemplateEmail(List<String> toList, String templateCode, Map<String, Object> templateParams);
    
    /**
     * 异步发送邮件
     * 
     * @param to 收件人邮箱
     * @param subject 邮件主题
     * @param content 邮件内容
     * @param isHtml 是否HTML格式
     * @return 发送结果 (返回记录ID)
     */
    Result<String> sendEmailAsync(String to, String subject, String content, boolean isHtml);
    
    /**
     * 异步发送模板邮件
     * 
     * @param to 收件人邮箱
     * @param templateCode 模板编码
     * @param templateParams 模板参数
     * @return 发送结果 (返回记录ID)
     */
    Result<String> sendTemplateEmailAsync(String to, String templateCode, Map<String, Object> templateParams);
    
    /**
     * 获取发送记录
     * 
     * @param recordId 记录ID
     * @return 发送记录
     */
    EmailRecord getRecord(String recordId);
    
    /**
     * 获取发送状态
     * 
     * @param recordId 记录ID
     * @return 发送状态
     */
    String getStatus(String recordId);
    
    /**
     * 重试发送
     * 
     * @param recordId 记录ID
     * @return 重试结果
     */
    Result<Boolean> retryEmail(String recordId);
    
    /**
     * 取消发送
     * 
     * @param recordId 记录ID
     * @return 取消结果
     */
    Result<Boolean> cancelEmail(String recordId);
    
    /**
     * 获取发送统计
     * 
     * @param timeRange 时间范围 (today, week, month)
     * @return 统计信息
     */
    Map<String, Object> getStatistics(String timeRange);
    
    /**
     * 处理待发送邮件队列
     * 
     * @return 处理数量
     */
    int processPendingEmails();
    
    /**
     * 清理过期邮件记录
     * 
     * @return 清理数量
     */
    int cleanExpiredRecords();
}
